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ABOUT THIS CHAPTER 


This chapter describes the Standard File Package, which provides the standard 
user interface for specifying a file to be opened or saved. The Standard File 
Package allows the file to be on a disk in any drive connected to the Macintosh, 


and 


You 


e 


lets a currently inserted disk be ejected so that another can be inserted. 
should already be familiar with: 


the basic concepts and structures behind QuickDraw, particularly points 
and rectangles 

the Toolbox Event Manager 

the Dialog Manager, especially the ModalDialog procedure 

packages in general, as described in the Package Manager chapter 
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ABOUT THE STANDARD FILE PACKAGE 


Standard Macintosh applications should have a File menu from which the user can 
Save and open documents, via the Save, Save As, and Open commands. In response 
to these commands, the application can call the Standard File Package to find 
out the document name and let the user switch disks if desired. As described 
below, a dialog box is presented for this purpose. 


When the user chooses Save As, or Save when the document is untitled, the 
application needs a name for the document. The corresponding dialog box lets the 
user enter the document name and click a button labeled "Save" (or just click 
"Cancel" to abort the command). By convention, the dialog box comes up 
displaying the current document name, if any, so the user can edit it. 


In response to an Open command, the application needs to know which document to 
open. The corresponding dialog box displays the names of all documents that 
might be opened; the user opens one by clicking it and then clicking a button 
labeled "Open", or simply by double-clicking on the document name. If there are 
more names than can be shown at once, the user can scroll through them using a 
vertical scroll bar, or type a character on the keyboard to cause the list to 
scroll to the first name beginning with that character. 


Both of these dialog boxes let the user: 


access a disk in an external drive connected to the Macintosh 

eject a disk from either drive and insert another 

initialize and name an inserted disk that's uninitialized 

switch from one drive to another or from one subdirectory to another 


eoeee 


On the right in the dialog box, separated from the rest of the box by a dotted 
line, there's a disk name with one or two buttons below it; Figure 1 shows what 
this looks like when an external drive is connected to the Macintosh but 
currently has no disk in it. Notice that the Drive button is inactive (dimmed). 
After the user inserts a disk in the external drive (and, if necessary, 
initializes and names it), the Drive button becomes active. If there's no 
external drive, the Drive button isn't displayed at all. 


| ee: 


Ein bares 


Figure 1—Partial Dialog Bor 
Figure 1—Partial Dialog Box 
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The disk name displayed in the dialog box is the name of the current disk, 
initially the disk from which the application was started. The user can click 
Eject to eject the current disk and insert another, which then becomes the 
current disk. If there's an external drive, clicking the Drive button changes 
the current disk from the one in the external drive to the one in the internal 
drive or vice versa. The Drive button is inactive whenever there's only one disk 
inserted. 


Note: Clicking the Drive button actually cycles through all volumes in 
drives currently connected to the Macintosh. (Volumes and drives are 
discussed in the File Manager chapter. ) 


If an uninitialized or otherwise unreadable disk is inserted, the Standard File 
Package calls the Disk Initialization Package to provide the standard user 
interface for initializing and naming a disk. 


Note: The remainder of this section discusses the enhanced Standard File 
Package which is only available in the 128K and later ROMs. 


The Standard File Package has been modified to work with the hierarchical file 
system. (This chapter assumes some familiarity with the material presented in 
the File Manager chapter.) Since a volume's files are no longer necessarily 
contained in a single flat directory, the Standard File Package must provide 
some way for the user to select a file that's contained in a folder (or 
subdirectory). It must also provide the user with a way of indicating the 
directory into which a particular file should be saved. 


The dialog box displayed in response to the SFGetFile procedure shows the names 
of folders (if any) as well as files. Files and folders are distinguished by 
miniature icons preceding their names. Notice that there are two types of mini- 
icons for files—one for applications and another for documents. Figure 2 shows 
the files and folders contained on a sample desktop. 
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Figure 2-Open Dialog (at the Desktop Level} 
Figure 2—Open Dialog (at the Desktop Level) 
To view the files and folders contained in a particular folder, the user must 
open the folder by clicking it and then clicking the Open button, or by double- 


clicking on the folder name; this causes the contents of the folder to be 
displayed. Figure 3 shows the contents of the sample folder special. 


—] special 
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2 threat 


Figure 3-Open Dialog (at a Folder Level) 


Figure 3—Open Dialog (at a Folder Level) 
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A current directory button above the list shows the name of the directory whose 
files and folders are displayed in the list below. If the contents of the 
desktop (or root directory) are being displayed, the button will show the name 
of the volume next to either a 3 1/2-inch disk mini-icon or a hard disk mini- 
icon (as in Figure 2). If the contents of a particular folder (or subdirectory) 
are being displayed, the button will show the name of that folder next to an 
open folder mini-icon (as in Figure 3 for instance). 


Assembly-language note: The global variable SFSaveDisk always contains the 
negative of the volume reference number (never a 
working directory reference number) of the volume 
to use. If the hierarchical version of the File 
Manager is running, the global variable CurDirStore 
contains the directory ID of whatever directory 
(including the root) was last opened (regardless of 
whether a document was actually opened or saved). 
With the 64K ROM version of the File Manager, 
CurDirStore is not needed and is set to 0. 


e*eClick on the X-Ref button, and refer to Technical Note #80.+e« 


The current directory button provides a way of moving back up through the 
hierarchical directory structure of a volume. If the user is at the level of a 
particular folder (or subdirectory), clicking on the button causes a list to pop 
down. This list gives the path from the current directory back up to the root 
directory. The rules for displaying and selecting items from this "pop down" 
list are identical to those for items in a menu. To change levels, select the 
desired folder and the files and folders at that level will be displayed. 


When the user chooses Save As, or Save when the document is untitled, the 
SFPutFile dialog box contains a list of files and folders similar to the list 
displayed in response to the Open command. This allows the user to specify the 
directory into which the file should be placed. A current directory button above 
the list lets the user move about in the hierarchical structure. File names in 
the list are dimmed (but displayed, so that the user can see what other files 
are in the directory). Figure 4 shows an example. 
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Figure 4—Save Dialog Box (at the Desktop Lerel) 
Figure 4—-Save Dialog Box (at the Desktop Level) 


In both dialog boxes, the Drive, Eject, and Open/Save buttons function as they 
always have, although their positions have changed. The Save button is always 
dimmed if the current volume is locked. 


Note: No new buttons have been added, so programmers need not worry about 
interference with controls they've added. The new dialog boxes, 
however, are larger than the old boxes; the Standard File Package 
does its best to position nonstandard dialogs in a visible and 
pleasing position. (Additional details are provided below in the 
section "Creating Your Own Dialog Box". ) 


When the user dismisses the dialog, whether by Cancel or Save or Open, the 
directory currently displayed is set to be the working directory (in other 
words, a call is made to the File Manager function OpenwD). 
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USING THE STANDARD FILE PACKAGE 


The Standard File Package and the resources it uses are automatically read into 
memory when one of its routines is called. It in turn reads the Disk 
Initialization Package into memory if a disk is ejected (in case an 
uninitialized disk is inserted next); together these packages occupy about 8.5K 
to 10K bytes, depending on the number of files on the disk. 


Call SFPutFile when your application is to save to a file and needs to get the 
name of the file from the user. Standard applications should do this when the 
user chooses Save As from the File menu, or Save when the document is untitled. 
SFPutFile displays a dialog box allowing the user to enter a file name. 


Similarly, SFGetFile is useful whenever your application is to open a file and 
needs to know which one, such as when the user chooses the Open command from a 
standard application's File menu. SFGetFile displays a dialog box with a list of 
file names to choose from. 


You pass these routines a reply record, as shown below, and they fill it with 
information about the user's reply. 


TYPE SFReply = RECORD 


good: BOOLEAN; {FALSE if ignore command} 
copy: BOOLEAN; {not used} 
fType: OSType; {file type or not used} 
vRefNum: INTEGER; {volume reference number} 
version: INTEGER; {file's version number} 
fName: STRING[63] {file name} 

END; 


The first field of this record determines whether the file operation should take 
place or the command should be ignored (because the user clicked the Cancel 
button in the dialog box). The fType field is used by SFGetFile to store the 
file's type. The vRefNum, version, and fName fields identify the file chosen by 
the user; the application passes their values on to the File Manager routine 
that does the actual file operation. VRefNum contains the volume reference 
number of the volume containing the file. The version field always contains 0; 
the use of nonzero version numbers is not supported by this package. For more 
information on files, volumes, and file operations, see the File Manager 
chapter. 


Assembly-language note: Before calling a Standard File Package routine, if 
you set the global variable SFSaveDisk to the negative 
of a volume reference number, Standard File will use 
that volume and display its name in the dialog box. 
(Note that since the volume reference number is 
negative, you set SFSaveDisk to a positive value.) 


eeeClick on the X-Ref button, and refer to Technical Note #80.¢e« 
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Both SFPutFile and SFGetFile allow you to use a nonstandard dialog box; two 
additional routines, SFPPutFile and SFPGetFile, provide an even more convenient 
and powerful way of doing this. 


Applications that use the Standard File Package properly need no modification to 
operate on machines equipped with the 128K ROM. The specification of a directory 
in the SFGetFile and SFPutFile procedures is transparent, due to the fact that 
working directory reference numbers can always be used in place of volume 
reference numbers. (The relationship between volume reference numbers and 
working directory reference numbers is described in detail in the File Manager 
chapter.) If the user specifies that a given file be opened from or saved to a 
particular subdirectory, the vRefNum field of the reply record you pass with 
these routines will be filled with a working directory reference number instead 
of a volume reference number. 


Warning: Programmers who have written their own "standard file" routines or 
who rely on SFReply.vRefNum being a volume reference number may 
find that their applications are not compatible with the 128K ROM 
version of the File Manager. 


Using the Keyboard 


The Standard File Package lets you use a variety of keyboard keys to respond to 
its dialogs. The following special keys (or key sequences) are defined: 


Key Sequence Action 

Up Arrow Scrolls up (backward) through displayed list 
Down Arrow Scrolls down (forward) through displayed list 
Command—Up Arrow Closes the current directory 

Command—Down Arrow Opens the selected directory 

Command—Shift—1 Ejects disk in internal drive 

Command—Shi ft—2 Ejects disk in external drive 

Tab Equivalent to Drive button 

Return Equivalent to either Open or Save button 
Enter Same as Return 


Note: The Up Arrow and Down Arrow keys are available on the standard 
Macintosh Plus keyboard, and on the optional numeric keypad for 
the Macintosh 128K and 512K, as well as on the Macintosh XL keypad. 
(See the Macintosh User Interface Guidelines chapter for details on 
using the arrow keys.) In addition, with the SFGetFile dialog the 
user can type characters to locate files in the list; each time a 
character is typed, the list selects and displays the first file 
whose initial character matches the typed character. 
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STANDARD FILE PACKAGE ROUTINES 


Assembly-language note: The trap macro for the Standard File Package is 


_Pack3. The routine selectors are as follows: 


sfPutFile . EQU 1 
sfGetFile . EQU 2 
sfPPutFile . EQU 3 
sfPGetFile . EQU 4 


PROCEDURE SFPutFile (where: Point; prompt: Str255; origName: Str255; 


dlgHook: ProcPtr; VAR reply: SFReply); 


SFPutFile displays a dialog box allowing the user to specify a file to which 
data will be written (as during a Save or Save As command). It then repeatedly 
gets and handles events until the user either confirms the command after 
entering an appropriate file name or aborts the command by clicking Cancel in 
the dialog. It reports the user's reply by filling the fields of the reply 
record specified by the reply parameter, as described above; the fType field of 
this record isn't used. 


The general appearance of the standard SFPutFile dialog box is shown in Figure 
3. The where parameter specifies the location of the top left corner of the 
dialog box in global coordinates. The prompt parameter is a line of text to be 
displayed as a statText item in the dialog box, where shown in Figure 3. The 
origName parameter contains text that appears as an enabled, selected editText 
item; for the standard document-saving commands, it should be the current name 
of the document, or the empty string (to display an insertion point) if the 
document hasn't been named yet. 


If you want to use the standard SFPutFile dialog box, pass NIL for dlgHook; 
otherwise, see the information for advanced programmers below. 


SFPutFile repeatedly calls the Dialog Manager procedure ModalDialog. When an 


event involving an enabled dialog item occurs, ModalDialog handles the event and 


returns the item number, and SFPutFile responds as follows: 


e 


If the Eject or Drive button is clicked, or a disk is inserted, 
SFPutFile responds as described above under "About the Standard File 
Package". 

Text entered into the editText item is stored in the fName field of 

the reply record. (SFPutFile keeps track of whether there's currently 
any text in the item, and makes the Save button inactive if not.) 

If the Save button is clicked, SFPutFile determines whether the file 
name in the fName field of the reply record is appropriate. If so, it 
returns control to the application with the first field of the reply 
record set to TRUE; otherwise, it responds accordingly, as described 
below. 

If the Cancel button in the dialog is clicked, SFPutFile returns control 
to the application with the first field of the reply record set to FALSE. 
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Note: 


Notice that disk insertion is one of the user actions listed above, 
even though ModalDialog normally ignores disk-inserted events. The 
reason this works is that SFPutFile calls ModalDialog with a 
filterProc function that lets it receive disk-inserted events. 


The situations that may cause an entered name to be inappropriate, and 
SFPutFile's response to each, are as follows: 


e 


Note: 


If a file with the specified name already exists on the disk and is 
different from what was passed in the origName parameter, the alert 
in Figure 5 is displayed. If the user clicks Yes, the file name is 
appropriate. 


with the selected items? 


A Replace items with the same names 


Figure 5—Alert for Existing File 
Figure 5-Alert for Existing File 


If the disk to which the file should be written is locked, the alert 
in Figure 6 is displayed. If a system error occurs, a similar alert 

is displayed, with the message "A system error occurred; please try 

again" (this is unrelated to the fatal system errors reported by the 
System Error Handler). 


The disk is locked. 


Figure 6-—Alert for Locked Disk 
Figure 6—-Alert for Locked Disk 


The user may specify a disk name (preceding the file name and 
separated from it by a colon). If the disk isn't currently in a 
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drive, an alert similar to the one in Figure 6 is displayed. 
The ability to specify a disk name is supported for historical 
reasons only; users should not be encouraged to do it. 


After the user clicks No or Cancel in response to one of these alerts, SFPutFile 
dismisses the alert box and continues handling events (so a different name may 
be entered). 


Advanced programmers: You can create your own dialog box rather than use the 
standard SFPutFile dialog. However, future compatibility 
is not guaranteed if you don't use the standard 
SFPutFile dialog. To create a nonstandard dialog, you 
must provide your own dialog template and store it in 
your application's resource file with the same resource 
ID that the standard template has in the system resource 
file: 


CONST putDlgID = -3999; {SFPutFile dialog template ID} 
eeeClick on the X-Ref button, and refer to Technical Note #47.¢ee 


Note: The SFPPutFile procedure, described below, lets you use any resource 
ID for your nonstandard dialog box. 


Your dialog template must specify that the dialog window be invisible, and your 
dialog must contain all the standard items, as listed below. The appearance and 
location of these items in your dialog may be different. You can make an item 
"invisible" by giving it a display rectangle that's off the screen. The display 
rectangle for each item in the standard dialog box is given below. The rectangle 
for the standard dialog box itself is (0,0) (304,104). 


Item number Item Standard display rectangle 

1 Save button (12,74) (82,92) 

2 Cancel button (114,74) (184,92) 
3 Prompt string (statText) (12,12) (184,28) 
4 UserItem for disk name (209,16) (295,34) 
5 Eject button (217,43) (287,61) 
6 Drive button (217,74) (287,92) 
7 EditText item for file name (14,34) (182,50) 

8 UserItem for dotted line (200,16) (201,88) 


Note: Remember that the display rectangle for any "invisible" text item must 
be at least about 20 pixels wide. 


If your dialog has additional items beyond the standard ones, or if you want to 
handle any of the standard items in a nonstandard manner, you must write your 
own dlgHook function and point to it with dlgHook. Your dlgHook function should 
have two parameters and return an integer value. For example, this is how it 
would be declared if it were named MyDlg: 


FUNCTION MyDlg (item: INTEGER; theDialog: DialogPtr) : INTEGER; 


Immediately after calling ModalDialog, SFPutFile calls your dlgHook function, 
passing it the item number returned by ModalDialog and a pointer to the dialog 
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record describing your dialog box. Using these two parameters, your dlgHook 
function should determine how to handle the event. There are predefined 
constants for the item numbers of standard enabled items, as follows: 


CONST putSave Si {Save button} 
putCancel = 2; {Cancel button} 
putEject =5; {Eject button} 
putDrive = 6; {Drive button} 
putName = 7; {editText item for file name} 


After handling the event (or, perhaps, after ignoring it) the dlgHook function 
must return an item number to SFPutFile. If the item number is one of those 
listed above, SFPutFile responds in the standard way; otherwise, it does 
nothing. 


Note: For advanced programmers who want to change the appearance of the 
alerts displayed when an inappropriate file name is entered, the 
resource IDs of those alerts in the system resource file are listed 


below. 
Alert Resource ID 
Disk not found —3994 
System error —3995 
Existing file —3996 
Locked disk —3997 


PROCEDURE SFPPutFile (where: Point; prompt: Str255; origName: Str255; 
dlgHook: ProcPtr; VAR reply: SFReply; dlgID: INTEGER; 
filterProc: ProcPtr); 


SFPPutFile is an alternative to SFPutFile for advanced programmers who want to 
use a nonstandard dialog box. It's the same as SFPutFile except for the two 
additional parameters dlgID and filterProc. 


DlgID is the resource ID of the dialog template to be used instead of the 
standard one (so you can use whatever ID you wish rather than the same one as 
the standard). 


The filterProc parameter determines how ModalDialog will filter events when 
called by SFPPutFile. If filterProc is NIL, ModalDialog does the standard 
filtering that it does when called by SFPutFile; otherwise, filterProc should 
point to a function for ModalDialog to execute after doing the standard 
filtering. The function must be the same as one you would pass directly to 
ModalDialog in its filterProc parameter. (See the Dialog Manager chapter for 
more information. )PROCEDURE SFGetFile (where: Point; prompt: Str255; 
fileFilter: ProcPtr; 

numTypes: INTEGER; typeList: SFTypeList; 

dlgHook: ProcPtr; VAR reply: SFReply); 


SFGetFile displays a dialog box listing the names of a specific group of files 
from which the user can select one to be opened (as during an Open command). It 
then repeatedly gets and handles events until the user either confirms the 
command after choosing a file name or aborts the command by clicking Cancel in 
the dialog. It reports the user's reply by filling the fields of the reply 
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record specified by the reply parameter, as described above under "Using the 
Standard File Package". 


The general appearance of the standard SFGetFile dialog box is shown in Figure 
1. File names are sorted in order of the ASCII codes of their characters, 
ignoring diacritical marks and mapping lowercase characters to their uppercase 
equivalents. If there are more file names than can be displayed at one time, the 
scroll bar is active; otherwise, the scroll bar is inactive. 


The where parameter specifies the location of the top left corner of the dialog 
box in global coordinates. The prompt parameter is ignored; it's there for 
historical purposes only. 


The fileFilter, numTypes, and typeList parameters determine which files appear 
in the dialog box. SFGetFile first looks at numTypes and typeList to determine 
what types of files to display, then it executes the function pointed to by 
fileFilter (if any) to do additional filtering on which files to display. File 
types are discussed in the Finder Interface chapter. For example, if the 
application is concerned only with pictures, you won't want to display the names 
of any text files. 


Pass —l1 for numTypes to display all types of files; otherwise, pass the number 
of file types (up to 4) that you want to display, and pass the types themselves 
in typeList. The SFTypeList data type is defined as follows: 


TYPE SFTypeList = ARRAY[Q..3] OF OSType; 


Assembly-language note: If you need to specify more than four types, pass a 
pointer to an array with the desired number of entries. 


If fileFilter isn't NIL, SFGetFile executes the function it points to for each 
file, to determine whether the file should be displayed. The fileFilter function 
has one parameter and returns a Boolean value. For example: 


FUNCTION MyFileFilter (paramBlock: ParmBlkPtr) : BOOLEAN; 


SFGetFile passes this function the file information it gets by calling the File 
Manager procedure GetFileInfo (see the File Manager chapter for details). The 

function selects which files should appear in the dialog by returning FALSE for 
every file that should be shown and TRUE for every file that shouldn't be shown. 


Note: As described in the File Manager chapter, a flag can be set that tells 
the Finder not to display a particular file's icon on the desktop; 
this has no effect on whether SFGetFile will list the file name. 


If you want to use the standard SFGetFile dialog box, pass NIL for dlgHook; 
otherwise, see the information for advanced programmers below. 


Like SFPutFile, SFGetFile repeatedly calls the Dialog Manager procedure 
ModalDialog. When an event involving an enabled dialog item occurs, ModalDialog 
handles the event and returns the item number, and SFGetFile responds as 
follows: 


e If the Eject or Drive button is clicked, or a disk is inserted, 
SFGetFile responds as described above under "About the Standard File 
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Package". 

e If clicking or dragging occurs in the scroll bar, the contents of the 
dialog box are redrawn accordingly. 

e If a file name is clicked, it's selected and stored in the fName field 
of the reply record. (SFGetFile keeps track of whether a file name is 
currently selected, and makes the Open button inactive if not.) 

e If the Open button is clicked, SFGetFile returns control to the 
application with the first field of the reply record set to TRUE. 

¢ If a file name is double-clicked, SFGetFile responds as if the user 
clicked the file name and then the Open button. 

e If the Cancel button in the dialog is clicked, SFGetFile returns control 
to the application with the first field of the reply record set to FALSE. 


If a character key is pressed, SFGetFile selects the first file name starting 
with the character typed, scrolling the list of names if necessary to show the 
selection. If no file name starts with the character, SFGetFile selects the 
first file name starting with a character whose ASCII code is greater than the 
character typed. 


Advanced programmers: You can create your own dialog box rather than use the 
standard SFGetFile dialog. However, future compatibility 
is not guaranteed if you don't use the standard 
SFGetFile dialog. To create a nonstandard dialog, you 
must provide your own dialog template and store it in 
your application's resource file with the same resource 
ID that the standard template has in the system resource 
file: 


CONST getDlgID = -4000; {SFGetFile dialog template ID} 


Note: The SFPGetFile procedure, described below, lets you use any resource 
ID for your nonstandard dialog box. 


Your dialog template must specify that the dialog window be invisible, and your 
dialog must contain all the standard items, as listed below. The appearance and 
location of these items in your dialog may be different. You can make an item 
"invisible" by giving it a display rectangle that's off the screen. The display 
rectangle for each item in the standard dialog box is given below. The rectangle 
for the standard dialog box itself is (0,0) (348,136). 


Item number Item Standard display rectangle 
1 Open button (152,28) (232,46) 
2 Invisible button (1152,59) (1232,77) 
3 Cancel button (152,90) (232,108) 
4 UserItem for disk name (248 , 28) (344,46) 
5 Eject button (256,59) (336,77) 
6 Drive button (256,90) (336,108) 
7 UserItem for file name list (12,11) (125,125) 
8 UserItem for scroll bar (124,11) (140,125) 
9 UserItem for dotted line (244,20) (245,116) 
10 Invisible text (statText) (1044, 20) (1145,116) 


If your dialog has additional items beyond the standard ones, or if you want to 
handle any of the standard items in a nonstandard manner, you must write your 
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own dlgHook function and point to it with dlgHook. Your dlgHook function should 
have two parameters and return an integer value. For example, this is how it 
would be declared if it were named MyDlg: 


FUNCTION MyDlg (item: INTEGER; theDialog: DialogPtr) : INTEGER; 


Immediately after calling ModalDialog, SFGetFile calls your dlgHook function, 
passing it the item number returned by ModalDialog and a pointer to the dialog 
record describing your dialog box. Using these two parameters, your dlgHook 
function should determine how to handle the event. There are predefined 
constants for the item numbers of standard enabled items, as follows: 


CONST getOpen = 1; {Open button} 
getCancel = 3; {Cancel button} 
getEject =5; {Eject button} 
getDrive = 6; {Drive button} 
getNmList = 7; {userItem for file name list} 
getScroll = 8; {userItem for scroll bar} 


ModalDialog also returns "fake" item numbers in the following situations, which 
are detected by its filterProc function: 


e When it receives a null event, it returns 100. Note that since it calls 
GetNextEvent with a mask that excludes disk-inserted events, ModalDialog 
sees them as null events, too. 

e When a key-down event occurs, it returns 1000 plus the ASCII code of the 
character. 


After handling the event (or, perhaps, after ignoring it) your dlgHook function 
must return an item number to SFGetFile. If the item number is one of those 
listed above, SFGetFile responds in the standard way; otherwise, it does 
nothing. 


PROCEDURE SFPGetFile (where: Point; prompt: Str255; fileFilter: ProcPtr; 
numTypes: INTEGER; typeList: SFTypeList; 
dlgHook: ProcPtr; VAR reply: SFReply; dlgID: INTEGER; 
filterProc: ProcPtr); 


SFPGetFile is an alternative to SFGetFile for advanced programmers who want to 
use a nonstandard dialog box. It's the same as SFGetFile except for the two 
additional parameters dlgID and filterProc. 


DlgID is the resource ID of the dialog template to be used instead of the 
standard one (so you can use whatever ID you wish rather than the same one as 
the standard). 


The filterProc parameter determines how ModalDialog will filter events when 
called by SFPGetFile. If filterProc is NIL, ModalDialog does the standard 
filtering that it does when called by SFGetFile; otherwise, filterProc should 
point to a function for ModalDialog to execute after doing the standard 
filtering. The function must be the same as one you would pass directly to 
ModalDialog in its filterProc parameter. (See the Dialog Manager chapter for 
more information.) Note that the standard filtering will detect key-down events 
only if the dialog template ID is the standard one. 
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CREATING YOUR OWN DIALOG BOX 


This section is for advanced programmers who want to create their own dialog 
boxes rather than use the standard SFPutFile and SFGetFile dialogs. 


Note: This section discusses the enhanced Standard File Package 
which is only available in the 128K and later ROMs. 


Warning: Future compatibility is not guaranteed if you don't use the standard 
dialogs. 


eeeClick on the X-Ref button, and refer to Technical Note #47.+ee« 


The addition of the file name list to the SFPutFile dialog, as well as the 
addition of current directory buttons to both SFPutFile and SFGetFile, requires 
that the dialog boxes for each call be made larger and the items in the box 
moved down. Although new dialog templates and item lists are provided, the 
Standard File Package also needs an algorithm for transforming old or 
nonstandard dialog templates and item lists. 


To maintain compatibility with existing applications, the Standard File Package 
uses only the existing dialog items. In SFPutFile, a userItem for the new file 
name list replaces the dotted line in item number 8. In SFGetFile, the scroll 
bar userItem in item number 8 is no longer used. For both SFPutFile and 
SFGetFile, the information for the current directory button and the scroll bars 
is maintained internally. 


The Standard File Package determines if a dialog needs to be transformed by 
looking at the width of item number 8 (the dotted line or scroll bar) as 
specified in the item's rectangle. If the width of item number 8 specifies 
either a dotted line (a width of 1) or a scroll bar (a width of 16), the dialog 
will be transformed. 


Note: If a dialog needs to be transformed, the box is enlarged to make room 
for both the scrolling list and the current directory button. All of 
the items are moved down to their original position relative to the 
bottom of the box, and the scrolling list and current directory button 
are added. The dialog is then centered on the screen. If it overlaps 
the menu bar, it's moved down. If it extends below or to the right of 
the screen, it's repositioned to make the entire dialog visible. In the 
case of certain unusual dialogs, the bottom of the dialog may not be 
visible. 


To create nonstandard dialogs that will not be transformed (in other words, ones 
in which you leave room for the list and current directory button), simply set 
item number 8 to the desired size and location of your file name list, including 
scroll bars (for SFPutFile), and set item number 8 to have a width other than 16 
(for SFGetFile). The scroll bar is placed within the specified file name list's 
rectangle. 
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The DlgHook Function 


In the old Standard File Package, a dlgHook routine could not accurately monitor 
what file was being opened, since it could not detect a double-click. In the new 
Standard File Package, double-clicks on files are interpreted as clicks on the 
Open button (item number 1), allowing the dlgHook to intercept files to be 
opened. With folders, however, both clicks on the Open button and double-clicks 
are passed to the hook as "fake" item number 103. 


A new fake item number 102 is generated by a click in the current directory 
button; it causes the file list to be pulled down and tracked. 


To redisplay the file list in GetFile (which you might do if your dialog box 
contains radio buttons that let you choose different file types to be 
displayed), change item number 100 (a null event) into item number 101 (which 
means redisplay the list) from within the dialog hook. 


Note: Disk-inserted events are handled internally; they are not (and never 
have been) returned as "fake" item number 100. Item number 100 is 
returned only when no event has taken place. 


Before the dlgHook routine is called, information for the selected file or 
folder is stuffed in the reply record (which can be examined on null events). If 
no file or folder is selected, fName and fType are both NIL. If a file is 
selected, fName will not be NIL and will contain the file name. If a folder is 
selected, fType will not be NIL and will contain the dirID. This is done before 
the dialog hook is called, regardless of which event is being returned. 


Three of the new Standard File Package alerts display an OK button instead of a 
Cancel button: 


Alert Resource ID 
Disk not found —3994 
System error —3995 
Locked disk —3997 


Also, the text of the alert number —3994 (previously "Can't find that disk.") 
has been changed to "Bad character in name, or can't find that disk." This 
reflects the fact that this alert is generated if there's a colon in the name. 


With nonhierarchical volumes, SFGetFile passes the fileFilter function the file 
information it gets by calling the File Manager function GetFileInfo. With 
hierarchical volumes, it gets this information from the GetCatInfo function. 
SFPutFile does not support a fileFilter function. 
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SUMMARY OF THE STANDARD FILE PACKAGE 


Constants 

CONST 
{ SFPutFile dialog template ID } 
putDlgID = -3999; 


{ Item numbers of enabled items in SFPutFile dialog } 


putSave = {Save button} 

putCancel = 2; {Cancel button} 

putEject = 5; {Eject button} 

putDrive = 6; {Drive button} 

putName = 7; {editText item for file name} 


{ SFGetFile dialog template ID } 
getDlgID = -4000; 


{ Item numbers of enabled items in SFGetFile dialog } 


getOpen = 1; {Open button} 
getCancel = 3; {Cancel button} 
getEject =5; {Eject button} 
getDrive = 6; {Drive button} 
getNmList = 7; {userItem for file name list} 
getScroll = 8; {userItem for scroll bar} 
Data Types 
TYPE 
SFReply = RECORD 
good: BOOLEAN; {FALSE if ignore command} 
copy: BOOLEAN; {not used} 
fType: OSType; {file type or not used} 
vRefNum: INTEGER; {volume reference number} 
version: INTEGER; {file's version number} 
fName: STRING[63] {file name} 
END; 
SFTypeList = ARRAY[0..3] OF OSType; 
Routines 
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PROCEDURE SFPutFile (where: Point; prompt: Str255; origName: Str255; 
dlgHook: ProcPtr; VAR reply: SFReply); 

PROCEDURE SFPPutFile (where: Point; prompt: Str255; origName: Str255; 
dlgHook: ProcPtr; VAR reply: SFReply; dlgID: INTEGER; 
filterProc: ProcPtr); 

PROCEDURE SFGetFile (where: Point; prompt: Str255; fileFilter: ProcPtr; 
numTypes: INTEGER; typeList: SFTypeList; 
dlgHook: ProcPtr; VAR reply: SFReply); 

PROCEDURE SFPGetFile (where: Point; prompt: Str255; fileFilter: ProcPtr; 
numTypes: INTEGER; typeList: SFTypeList; 
dlgHook: ProcPtr; VAR reply: SFReply; dlgID: INTEGER; 
filterProc: ProcPtr); 


DlgHook Function 


FUNCTION MyDlg (item: INTEGER; theDialog: DialogPtr) : INTEGER; 


FileFilter Function 


FUNCTION MyFileFilter (paramBlock: ParmBlkPtr) : BOOLEAN; 


Standard SFPutFile Items 


Item number Item Standard display rectangle 

1 Save button (12,74) (82,92) 

2 Cancel button (114,74) (184,92) 
3 Prompt string (statText) (12,12) (184,28) 

4 UserItem for disk name (209,16) (295,34) 
5 Eject button (217,43) (287,61) 
6 Drive button (217,74) (287,92) 
7 EditText item for file name (14,34) (182,50) 
8 UserItem for dotted line (200,16) (201,88) 


Resource IDs of SFPutFile Alerts 


Alert Resource ID 
Disk not found —3994 
System error —3995 
Existing file —3996 
Locked disk —3997 


Standard SFGetFile Items 
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Item number Item Standard display rectangle 


1 Open button (152,28) (232,46) 
2 Invisible button (1152,59) (1232,77) 
3 Cancel button (152,90) (232,108) 
4 UserItem for disk name (248 ,28) (344,46) 
5 Eject button (256,59) (336,77) 
6 Drive button (256,90) (336,108) 
7 UserItem for file name list (12,11) (125,125) 
8 UserItem for scroll bar (124,11) (140,125) 
9 UserItem for dotted line (244,20) (245,116) 
10 Invisible text (statText) (1044, 20) (1145,116) 


Assembly-Language Information 
Constants 

; SFPutFile dialog template ID 
putDlgID . EQU -3999 


; Item numbers of enabled items in SFPutFile dialog 


putSave .EQU 1 ;Save button 

putCancel .EQU 2 ;Cancel button 

putEject .EQU 5 ;Eject button 

putDrive . EQU 6 ;Drive button 

putName . EQU 7 ;editText item for file name 


; SFGetFile dialog template ID 
getDlgID .EQU - 4000 


; Item numbers of enabled items in SFGetFile dialog 


getOpen . EQU 1 ;Open button 

getCancel .EQU 3 ;Cancel button 

getEject .EQU 5 ;Eject button 

getDrive . EQU 6 ;Drive button 

getNmList . EQU 7 ;userItem for file name list 
getScroll .EQU 8 ;userItem for scroll bar 
; Routine selectors 

sfPutFile . EQU 1 

sfGetFile .EQU 2 

sfPPutFile .EQU 3 

sfPGetFile .EQU 4 


Reply Record Data Structure 


rGood 0 if ignore command (byte) 
rType File type (long) 
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rVolume Volume reference number (word) 
rVersion File's version number (word) 
rName File name (length byte followed by up to 63 characters) 


Trap Macro Name 

_Pack3 

Variables 

SFSaveDisk Negative of volume reference number used by 
Standard File Package (word) 


CurDirStore Directory ID of directory last opened (long) 
SFSaveDisk Negative of volume reference number (word) 
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Further Reference: 


QuickDraw 

Toolbox Event Manager 

Dialog Manager 

Package Manager 

Technical Note #47, Customizing Standard File 
Technical Note #80, Standard File Tips 

Technical Note #99, Standard File Bug in System 3.2 
Technical Note #246, Mixing HFS and C File I/0 


END OF DOCUMENT 
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